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NGINX Plus deployed as an API gateway 


Source: NGINX brand survey 2017, 2018 


NGINX as an API Gateway 
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€ > С а GitHub, Inc. [US] | https://github.com/jcnewell/ergast-f1-api 


<> Code Issues 3 Pull requests 1 Projects 0 Wiki 


A PHP-based read-only API for the Ergast Formula One MySQL database 


XD 9 commits % 1 branch © 0 releases 


Branch: master ~ New pull request 


9 jcnewell Merge pull request #2 from psychemedia/master 
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Ва ergastdb Support for docker-compose execution a year ago 


а lamp Support for docker-compose execution a year ago 


а webroot Support for docker-compose execution a year ago 


LICENSE Initial commit 


README.md Remember to wait a mo... 


README.md 


ergast Local API Server 


2 years ago 


a year ago 


docker-compose.yaml Support for docker-compose execution a year ago 


Based on the ergast-f1-api , a PHP-based API using the Ergast Formula One MySQL database developed by Chris Newell. 


1. Organize config 


1. Organize configuration 


nginx.conf 
www.example.conf 


another. site.conf 
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1. Organize configuration 


= Е 
another_ | another ste con conf 


api_gateway.conf 


/etc/nginx 


= КЕЕ 
baseball.conf 


2. Single client-facing hostname 


api_gateway.conf 


log format api main 'Sremote_addr - $remote user [$time local] "$request" ' 
'$status S$body bytes sent "$http referer" ' 
'"$http user agent" "Shttp x forwarded for" "барі name"' 
nginx.conf 


include арі backends.conf; EN 
another. site.conf 


set барі name -; # Start with an undefined API name 
access log log/api access.log api main; 


listen 443 ssl; 


server name api .ехатрте. сот; 


api_gateway.conf 


api_backends.conf 


/etc/nginx 


ssl certificate /etc/nginx/ssl/api.example.com.crt; 


ssl certificate key  /etc/nginx/ssl/api.example.com.key; еи 
api_conf.d/ 


include api conf.d/*.conf; 
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3. Separate definition from policy 


f1results.conf 


# API definition 

# 

location = /api/f1 

location ~ /api/f1/[12][0-9]+ 


location /api/f1/current 
location /api/f1/seasons 
location /api/f1/status 
location /api/f1/drivers 
location /api/f1/circuits 
location /api/f1/constructors 


# Policy section 


一 一 一 一 一 一 一 一 


rewrite 
rewrite 
rewrite 
rewrite 
rewrite 
rewrite 
rewrite 
rewrite 


> > > > > > > > 


/_ergast 
/_ergast 
/_ergast 
/_ergast 
/_ergast 
/_ergast 
/_ergast 
/_ergast 


# 
location = /_ergast { 
internal; 
set Sapi_name "F1 results"; 
# Policy configuration here (authentication, rate 
proxy_pass http://ergast_apiSrequest_uri. json; 
} 


last; 
last. 
last; 
last; 
last; 
last; 
Пас; 
last; 


一 一 ~ 一 ~ 一 ~ 一 一 一 一 


limiting, logging, 


E) 


EH 

ар! gateway.conf 

api. backends.conf 
api. conf.d/ 


/etc/nginx 


baseball.conf 
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4. Microservices routing 


F1 results 
(monolith) 


Constructors 
microservice 


4. Microservices routin 


f1results.conf 


# API definition 


EW CI Jd O U O 


1 

2) H 

3 | location /api/f1 { rewrite * /_ergast_mono last; } 

4 | location /api/f1/drivers { rewrite ^ /_ergast_drivers last; } 
5 | location /api/f1/circuits { rewrite ^ /_ergast_circuits last; 

6 Е à аа 

7 

8 


EZH 


# Routing 


> 
c 

© (©), another_site.conf 
10 | location = /_ergast_mono { = api_gateway.conf 
11 proxy_pass http://f1_mono_apiSrequest_uri.json; ) 
12 + - 
13 location = /_ergast_drivers { а) api_backends.conf 
14 proxy_pass http://f1 drivers service$request uri.json; ~ 


} 
16 location = /_ergast_circuits { api_conf.d/ 
17 proxy_pass http://f1_circuits_serviceSrequest_uri.json; ЕТ 


18 Б) 

19 location = /_ergast_constructors { 

20 proxy_pass http://f1_constructors_serviceS$request_uri. json; 
21 |} 
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5. Send appropriate errors 


api_gateway.conf 


7 server { 


8 set Sapi_name -; # Start with an undefined API name 

9 access_log log/api_access.log api_main; 

: 
did listen 443 ssl; 

12 server name api.example.com; >< 

14 ssl_certificate /etc/nginx/ssl/api.example.com.crt; fe) api. gateway.conf 

15 ssl_certificate_key /etc/nginx/ssl/api.example.com.key; с 

16 - 

17 include api_conf.d/*.conf; о 

18 + = 

19 # Error responses ad) 

20 location / { | ~ 

21 return 404; # Catch-all for unrecognized URIs 

23 еггог_раде 404 = 6400; # Invalid paths are treated as bad requests 

24 proxy_intercept_errors on; # Do not send endpoint errors to the client xi 

25 include api. json err.conf; # API client friendly JSON error responses 
26 default_type application/json; # If no content-type then assume JSON 


21 
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5. Send appropriate JSON errors 


api_json_err.conf 


© соЈаслљо~м 


еггог_раде 400 = 6400; 
location @400 { return 


еггог_раде 401 = 6401; 
location 0401 { return 


еггог_раде 403 = 0403; 
location 0403 { return 


еггог_раде 404 = 0404; 
location 0404 { return 


еггог_раде 405 = 0405; 
location 0405 { return 


error_page 408 = 0408; 
location 0408 { return 


error_page 413 = @413; 
location @413 { return 


error_page 414 = @414; 
location @414 { return 


400 '{"status" :400, "message" 


401 


403 


404 


405 


408 


413 


414 


status. 


status. 


'{"status" 


'(" status" 


Estatus 


status. 


status. 


“491, "message" 


“403, "message" 


:404, "message" 


:405, "message" 


:408, "message" 


:413, "message" 


:414, "message" 


:"Bad request"}\n'; } 


:"Unauthorized"}\n'; } 


:"Forbidden"}\n'; } 


: "Resource not found"}\n'; } 


: "Method not allowed"}\n'; } 


: "Request timeout"}\n'; } 


:"Payload too large"}\n'; } 


:"URI too large"}\n'; } 


x 

= 
о 
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/etc/ 


EZH 


api. gateway.conf 


ар! backends.conf 


api. json. err.conf 


api. conf.d/ 


www.example.conf 
another. site.conf 


flresults.conf 
baseball.conf 
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5. Send appropriate gRPC errors 


api_grpc_err.conf 


# Standard HTTP-to-gRPC status code mappings 
# Ref: https://github.com/grpc/grpc/blob/master/doc/http-grpc-status-mapping.md 
# 

еггог_раде 400 = @grpc_internal; 

еггог_раде 401 @grpc_unauthenticated; 
error_page 403 = @grpc_permission_denied; 
error_page 404 @grpc_unimplemented; 
error_page 429 = @grpc_unavailable; 
error_page 502 = @grpc_unavailable; 
error_page 503 = @grpc_unavailable; 
error_page 504 = @grpc_unavailable; 


# gRPC error responses 
# Ref: https://github.com/grpc/grpc-go/blob/master/codes/codes.go 
# 
location @grpc_internal { 
add_header grpc-status 13; 
add header grpc-message ‘internal error’; 
return 204; 
} 


location @grpc_unauthenticated { 
add_header grpc-status 16; 
add_header grpc-message unauthenticated; 
return 204; 


x 
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= 


/etc/ 


EZH 


api. gateway.conf 


api. backends.conf 


api. grpc. err.conf 


api. conf.d/ 


www.example.conf 
another. site.conf 


flresults.conf 
baseball.conf 
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6. Limit authentication 
options 


6. Limit authentication options 


JWT B Client 
- NGINX Plus Cert 


HTTP 57 пу: 
Basic O Key 
Gateway 


7. Protect API keys 


api_gateway.conf 


29 include api_keys.conf 


31 js.include api_auth.js; 
32 js_set Sapikey_hash hashApikey; 


api_keys.conf 


1 пар Sapikey_hash Sapi_client_name { 

2 default ""; 

E 

4 “vvV+x/U6bUC+tkCngKY5yDvCmsipgW8fxsXG3Nk8RyE=" " 
5 "P7edLn93QUtR2PQd97EEKZEQkR1KkeOvU/rw1Je7gY0-" " 
6 "yorH9e21UcrLrgIz91DHIEBDYxy8YenXoN1pL1ncVKo-" 

7g | 


function hashApiKey(req) ( 


return h.digest('base64'); 
} 


"client three" 


1 
2 var c = require('crypto'); 

3 var h = о 
4 

5 


ШЕШЕН | 


another_site.conf 


> 
с api_gateway.conf 
е) 
Е ар! keys.conf 
#abcdef О 
; en D api backends.conf 
— 


api. conf.d/ U 


weather.conf 
api_auth.js 
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7. Protect API keys 


f1results.conf 


1 
2 
3 location /api/f1 { rewrite ^ /_ergast last; } 
4 location /api/f1/drivers { rewrite ^ /_ergast last; } ӘБИ! 
5 location /api/f1/circuits { rewrite ^ /_ergast last; } 
6 location /api/f1/constructors { rewrite ^ /_ergast last; } < | another-site:conf | site.conf 
U 
8 # Policy section с api_gateway.conf 
9 4 O 
10 location = / ergast { (= А 
11 internal; = api_keys.conf 
12 set Sapi_name "F1 results"; O 
+ 5 
# Policy configuration here (authentication, rate limiting, logging,\...) Ф api_backends.conf 
f (Shttp_apikey = "") { == 
return 401; # Unauthorized (please authenticate) 
api_conf. 
і Е i x | 
return 403; # Forbidden (invalid АРТ ke г у 
20 } api_auth.js 
21 
22 proxy_pass http://ergast api$request uri.json; 
290 |} 
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8. Know why youre rate limiting 


api_gateway.conf 


log_format api main 'Sremote_addr - 5гепоте user [Stime_local] "Srequest" 
'$status $body_bytes_sent "$http referer" ' 


'"$http. user agent" "Shttp x forwarded. for" "барі name"'; 
nginx.conf 
include арі backends.conf; 
БЕСЛЕ ren 


limit req zone $binary remote addr zone=client_ip_1@rps:1m rate-10r/s; 
limit req zone Shttp_apikey zone=apikey 200rps:1m rate-200r/s; 


f1results.conf 


12 # Policy section 
13 + 


14 location = /_ergast 4 2 
15 internal; api_conf.d/ 


со с س‎ + ою د‎ 


another_site.conf 


api_gateway.conf 


api_backends.conf 


/etc/nginx 


16 set барі name "F1 results"; 
17 

18 limit. req zone-apikey. 200rps; 

19 limit reg zone-client. ip. 10rps; 

20 limit req status 429; £ Too many requests 

21 


22 proxy_pass http://ergast_api$request_uri.json; 
2 ХВ 


9. Inspect the request 
methoo 


API Dimensions 


POST 


/api/f1/seasons /api/f1/seasons 


POST 


"season":2019, 
ер 


/api/f1/seasons 


9. Inspect the request method 


f1results.conf 


# API definition 
# 


1 
2 

3 location /api/f1 { Е 

4 limit_except СЕТ { deny all; ) nginx.conf 

7 

8 


rewrite ^ /_ergast last; 
шш. 
another_site.conf 
api_gateway.conf 


api_backends.conf 
16 # Policy/routing section api_conf.d/ 


location = /api/f1/seasons { 
limit_except GET POST { deny all; } 
if ( Srequest_method = POST ) { 


rewrite ^ /_ergast_masterdb last; 


} 


rewrite ^ /_ergast last; 


/etc/nginx 


А weather.conf 
18 location = /_ergast { 
19 internal; 
20 proxy_pass http://ergast_apiSrequest_uri. json; 
2015 
22 
23 location = /_ergast_masterdb { 
24 internal; MUS 
25 proxy_pass http://18.8.8.1$request_uri; 


10. Inspect body if necessary 


api_gateway.conf 


29 js_include json_validator.js; 


30 js_set Svalidated json_validator; 

E 

32 server ( www.example.conf 
33 listen 127.0.0.1:10415; # This is the error response of json_validator() EEN Д ре 

34 


return 415; # Unsupported media type < conf.d/ 
35 include api_json_err.conf; 
Beale с another_site.conf 
[e) api. gateway.conf 
: 5 : = 
json_validator.js — 
O 
1 function json_validator(req) { D firesults.conf 
2 try { = 
2 abr 
TE 
6 return req.variables.upstream; json_validator.js 
7 } catch (е) { 
8 req.log('JSON.parse exception’); 
9 return '127.0.0.1:10415' ; 
10 } 
11 
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10. Inspect body if necessary 


f1results.conf 


23 location = /_ergast_masterdb { 

24 internal; 

26 set Sapi_name "Ergast MRD"; 

= set Supstream ergast_api_master; 
= аре: шш 


29 client_body_in_single_buffer оп; >< 5 

30 client_max_body_size 16k; с 
31 (©), арі gateway.conf 

32 proxy_pass http://Svalidated; e 

33 } 


=== 
E 
+ 
Ф 
== 


api_gateway.conf 
20 # Dummy location used to populate $request body for JSON validation я idatoni 
30 location /_null { json_validator.js 


E internal; 

52 return 204; 

33 access_log off; 
34 } 
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€ С а https://gist.github.com/nginx-gists/6a8e7c65fdc41bc955f7e67a1d4754 


GitHubGist Search. Allgists GitHub Sign up for a GitHub account Е 


Instantly share code, notes, and snippets. 


БЕ nginx-gists / api gateway.conf *Star 3 рок 0 
eoe @ NGINX | High Performance Lo: X + 


< С а https://www.nginx.com а: 


SOLUTIONS RESOURCES SUPPOR PRICING — BLCG FRE= TRIAL 


include api keys.conf; 


limit req zone $binary remote addr zone-client ip 10г5:1т rate-10r/s; 


limit req zone $http apikey zone-apikey 200г5:11  rate-200r/s; 
server 5 
set $api name -; # Start with an undefined API name, each API will update this v 


access log /var/log/nginx/api access.log api main; # Each API may also log to a separate file 


listen 443 ssl; 
server name api.example.com; 


# TLS config 

ssl_certificate /еїс/551/сегїѕ/арі. ехатр1е. com. crt; 
ssl certificate key /etc/ssl/private/api.example.com. key; 
551 session cache shared:SSL:10m; 

ssl session timeout 5m; 


ssl ciphers HIGH: !aNULL : !MD5; 
ssl protocols TLSv1.1 TLSv1.2; 
# API definitions, one per file 


include api conf.d/x.conf; 


“---ы ~ 
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